"""
API 模块 - 控制器基类与路由装饰器

此模块提供了 `BaseController` 类，作为所有 API 控制器的推荐基类。
它通过提供 `@get`, `@post` 等类方法装饰器，实现了声明式的路由定义，
开发者无需直接与 FastAPI 的 APIRouter 交互。
"""
from typing import Callable, List, Any

# 注意：我们在这里不直接导入 APIRoute，因为这里的装饰器
# 只是收集路由信息，最终的路由对象将在
# ControllerProcessor 中创建。这避免了不必要的依赖。


class BaseController:
    """
    API 控制器的基类。

    子类通过继承此类，即可使用 `@get`, `@post` 等装饰器来声明路由。
    路由信息会被直接附加到端点函数上，由框架的 `ControllerProcessor` 在应用启动时
    自动发现和注册。
    """
    pass


def route(path: str, methods: List[str], **kwargs: Any) -> Callable:
    """
    一个内部装饰器，用于将路由元数据直接附加到端点函数上。

    Args:
        path: 路由的 URL 路径。
        methods: 一个 HTTP 方法的列表 (例如 ['GET', 'POST'])。
        **kwargs: 其他传递给 FastAPI 的 `add_api_route` 的参数
                  (例如 status_code, response_model 等)。

    Returns:
        返回一个装饰器，该装饰器会将路由信息附加到被装饰的方法上。
    """
    def decorator(endpoint: Callable) -> Callable:
        # 确保只在函数上附加一次列表
        if not hasattr(endpoint, '_axiom_route_info'):
            setattr(endpoint, '_axiom_route_info', [])

        # 将路由信息保存起来，待 ControllerProcessor 处理
        route_info = {
            'path': path,
            'methods': methods,
            **kwargs
        }
        
        # 将新的路由信息追加到列表中
        getattr(endpoint, '_axiom_route_info').append(route_info)

        return endpoint
    return decorator


# --- 便捷的 HTTP 方法装饰器 ---

def get(path: str, **kwargs: Any) -> Callable:
    """注册一个处理 GET 请求的路由。"""
    return route(path, methods=['GET'], **kwargs)

def post(path: str, **kwargs: Any) -> Callable:
    """注册一个处理 POST 请求的路由。"""
    return route(path, methods=['POST'], **kwargs)

def put(path: str, **kwargs: Any) -> Callable:
    """注册一个处理 PUT 请求的路由。"""
    return route(path, methods=['PUT'], **kwargs)

def delete(path: str, **kwargs: Any) -> Callable:
    """注册一个处理 DELETE 请求的路由。"""
    return route(path, methods=['DELETE'], **kwargs)

def patch(path: str, **kwargs: Any) -> Callable:
    """注册一个处理 PATCH 请求的路由。"""
    return route(path, methods=['PATCH'], **kwargs)

def head(path: str, **kwargs: Any) -> Callable:
    """注册一个处理 HEAD 请求的路由。"""
    return route(path, methods=['HEAD'], **kwargs)

def options(path: str, **kwargs: Any) -> Callable:
    """注册一个处理 OPTIONS 请求的路由。"""
    return route(path, methods=['OPTIONS'], **kwargs)